Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation on Perl packages. #1790

Open
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

ssurbhi560
Copy link
Contributor

Closes #1536

PR Checklist:

  • make all edits to the docs in the src directory, not in docs or in the html files
  • note any issues closed by this PR with closing keywords
  • put any other relevant information below

@ssurbhi560 ssurbhi560 requested a review from a team as a code owner June 27, 2022 11:12
Copy link
Contributor

@kathatherine kathatherine left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will be a good help to maintainers. Thanks for writing this up! I just have a few edits and questions.

src/maintainer/knowledge_base.rst Outdated Show resolved Hide resolved
src/maintainer/knowledge_base.rst Outdated Show resolved Hide resolved
src/maintainer/knowledge_base.rst Outdated Show resolved Hide resolved
src/maintainer/knowledge_base.rst Outdated Show resolved Hide resolved
src/maintainer/knowledge_base.rst Outdated Show resolved Hide resolved
src/maintainer/knowledge_base.rst Outdated Show resolved Hide resolved
src/maintainer/knowledge_base.rst Outdated Show resolved Hide resolved
@ssurbhi560
Copy link
Contributor Author

ssurbhi560 commented Jun 29, 2022

Thanks for taking the time to review the PR @jmarshall and @nsoranzo! :)
I will update it as you suggested.

@jmarshall
Copy link

This is good as far as it goes, and IMHO would usefully be merged as such.

Currently in bioconda there are 315 Perl packages using ExtUtils::MakeMaker and 119 using Module::Build. If the statistics for conda-forge are similar, it would be useful to add the corresponding advice for configuring Module::Build as well.

Copy link
Contributor

@kathatherine kathatherine left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A couple things. Great work!

src/maintainer/knowledge_base.rst Outdated Show resolved Hide resolved
src/maintainer/knowledge_base.rst Outdated Show resolved Hide resolved
src/maintainer/knowledge_base.rst Outdated Show resolved Hide resolved
Copy link
Contributor

@kathatherine kathatherine left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for adding that! I added a few rewrites.

Comment on lines +1580 to +1588
The other build system used for Perl packages is ``Module::Build``. ``Module::Build`` is a system for building, testing, and installing Perl modules.
It is an alternative to ``ExtUtils::MakeMaker``. It does not require ``make`` - most of the ``Module::Build`` code is pure Perl and written in a very cross-platform way.
The recipe of some of the Perl packages that uses ``Module::Build`` are :

- `perl-math-derivative <https://github.com/bioconda/bioconda-recipes/blob/master/recipes/perl-math-derivative/meta.yaml>`__
- `perl-graphics-colornames <https://github.com/bioconda/bioconda-recipes/blob/master/recipes/perl-graphics-colornames/meta.yaml>`__
- `mirnature <https://github.com/bioconda/bioconda-recipes/blob/master/recipes/mirnature/meta.yaml>`__

To know more about ``Module::Build`` and difference between the two build systems read `Comparison <https://metacpan.org/pod/Module::Build#COMPARISON>`__ and `Module::Build <https://metacpan.org/pod/Module::Build>`__.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The other build system used for Perl packages is ``Module::Build``. ``Module::Build`` is a system for building, testing, and installing Perl modules.
It is an alternative to ``ExtUtils::MakeMaker``. It does not require ``make`` - most of the ``Module::Build`` code is pure Perl and written in a very cross-platform way.
The recipe of some of the Perl packages that uses ``Module::Build`` are :
- `perl-math-derivative <https://github.com/bioconda/bioconda-recipes/blob/master/recipes/perl-math-derivative/meta.yaml>`__
- `perl-graphics-colornames <https://github.com/bioconda/bioconda-recipes/blob/master/recipes/perl-graphics-colornames/meta.yaml>`__
- `mirnature <https://github.com/bioconda/bioconda-recipes/blob/master/recipes/mirnature/meta.yaml>`__
To know more about ``Module::Build`` and difference between the two build systems read `Comparison <https://metacpan.org/pod/Module::Build#COMPARISON>`__ and `Module::Build <https://metacpan.org/pod/Module::Build>`__.
The other build system used for Perl packages is ``Module::Build``, which is a system for building, testing, and installing Perl modules.
It is an alternative to ``ExtUtils::MakeMaker``. It does not require ``make``; most of the ``Module::Build`` code is pure Perl and written in a very cross-platform way.
The recipes of some of the Perl packages that use ``Module::Build`` are:
- `perl-math-derivative <https://github.com/bioconda/bioconda-recipes/blob/master/recipes/perl-math-derivative/meta.yaml>`__
- `perl-graphics-colornames <https://github.com/bioconda/bioconda-recipes/blob/master/recipes/perl-graphics-colornames/meta.yaml>`__
- `mirnature <https://github.com/bioconda/bioconda-recipes/blob/master/recipes/mirnature/meta.yaml>`__
To know more about ``Module::Build`` and differences between the two build systems, see the `Module::Build <https://metacpan.org/pod/Module::Build>`__ page, paying special attention to the `Comparison <https://metacpan.org/pod/Module::Build#COMPARISON>`__ section.

@jmarshall
Copy link

With respect, the information that has been added about Module::Build is entirely not what this document's audience needs to know. The reader is packaging an existing Perl module that has already chosen between the two systems, so they already know what they are and don't need to know the pros and cons of each.

What this audience does need from this document is to be told the Module::Build equivalent of the recommended perl Makefile.PL INSTALLDIRS=vendor NO_PERLLOCAL=1 NO_PACKLIST=1 ExtUtils::MakeMaker incantation.

@ssurbhi560
Copy link
Contributor Author

Thanks John for letting me know about this. I am still quite new to this and all this was something I didn't know, so I ended up adding everything I found useful. But as you said this documentation would be used by someone already well versed with Perl packages so it would probably be irrelevant for them.

So, now, @kathatherine and @jmarshall what would you suggest - should I remove the all the information about Module::Build or may keep a sentence describing what Module::Build is and examples of recipes using perl-module-build?

@kathatherine
Copy link
Contributor

@ssurbhi560 At least one link to some information on Module::Build would be good, in my opinion, just for people who are newer to it. It could be useful to someone, even if the audience for this section is people who are more experienced in Purl. But as @jmarshall says, the most important thing is explaining how users can use Module::Build in the build section of their yaml instead of ExtUtils::MakeMaker. So a section like lines 1561 - 1574, just below that section, with the necessary Module::Build information instead. Am I correct, John?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Development

Successfully merging this pull request may close these issues.

Add Perl package hints to documentation
6 participants